fix: Add comprehensive TTL ledger testing and documentation - #218

Overview

This PR addresses Issue #85 by adding comprehensive TTL (Time-To-Live) ledger testing and documenting the archival/restoration story for Sharibo circles.

Changes

Contract Tests (contracts/sharibo/src/test.rs)

Added 3 new test cases to pin TTL behavior and verify persistent entry survival:

1. persistent_circle_survives_multiple_rounds_with_ttl_refresh

   • Creates a circle and funds/claims across 2 rounds
   • Advances ledger by LEDGER_THRESHOLD between operations to trigger TTL re-extension logic
   • Verifies that both Circle and Nullifier entries persist and remain accessible
   • Confirms TTL is actively refreshed on every write, not just at creation

2. circle_and_nullifier_entries_individually_extended

   • Tests that both the Circle persistent entry AND the Nullifier persistent entry are independently extended
   • Advances ledger past LEDGER_THRESHOLD and verifies both entries remain accessible
   • Pins that extend_ttl is called on both storage keys

3. ttl_survives_fund_after_ledger_advance

   • Tests fund operation after ledger advancement past LEDGER_THRESHOLD
   • Verifies that fund triggers TTL re-extension even at advanced ledger heights
   • Confirms indefinite circle activity is possible through continuous re-extension

Documentation Updates

Contract Code (contracts/sharibo/src/lib.rs)

Added detailed comments explaining TTL constants:

• LEDGER_THRESHOLD = 100: Re-extension trigger (~8.3 minutes at 5s/ledger)
• LEDGER_EXTEND_TO = 500_000: Target TTL (~29 days at 5s/ledger)

README (contracts/README.md)

Added new "TTL (Time-To-Live) & State Archival" section documenting:

• TTL mechanism and rationale
• Archival & Restoration Story:
  • Entries archived after 29+ days of inactivity
  • Restoration via permissionless RestoreFootprintOp
  • State preservation on restoration (no data loss)
  • Permissionless recovery (no admin key required)
  • Reference to Soroban documentation

Acceptance Criteria Met

✅ TTL behavior is pinned by test, not assumption
✅ Ledger advancement scenarios covered (threshold & beyond)
✅ Archival/restoration story documented
✅ TTL numbers' rationale recorded (~500k ledgers ≈ 29 days at 5s/ledger)
✅ Fund/claim operations verified to work after ledger advancement

Testing Notes

• All new tests use soroban-sdk's ledger controls (env.ledger().with_mut())
• Tests are compatible with existing test infrastructure
• No breaking changes to existing tests or contract behavior

Related Issue

closes #85